## 7.2. Making Our Own Indexes

In the last section, we looked at Apache's indexing facilities. So far we have not been very adventurous with our own indexing of the document root directory. We replaced Apache's adequate directory listing with a custom-made .html file: index.html (see Chapter 3, "Toward a Real Web Site").

We can improve on index.html with the `DirectoryIndex` command. This command specifies a list of possible index files to be used in order.

### 7.2.1. DirectoryIndex

>     DirectoryIndex local-url local-url ...
>     Default: index.html
>     Server config, virtual host, directory, .htaccess

The `DirectoryIndex` directive sets the list of resources to look for when the client requests an index of the directory by specifying a "/" at the end of the directory name. local-url is the (%-encoded) URL of a document on the server relative to the requested directory; it is usually the name of a file in the directory. Several URLs may be given, in which case the server will return the first one that it finds. If none of the resources exists and Options Indexes is set, the server will generate its own listing of the directory. For example, if the specification is:

>     DirectoryIndex index.html

then a request for http://myserver/docs/ would return http://myserver/docs/index.html if it exists, or would list the directory if it did not. Note that the documents do not need to be relative to the directory:

>     DirectoryIndex index.html index.txt /cgi-bin/index.pl

would cause the CGI script /cgi-bin/index.pl to be executed if neither index.html or index.txt existed in a directory.

The Config file from ... /site.ownindex is as follows:

>     User webuser
>     Group webgroup
>     ServerName www.butterthlies.com
>     DocumentRoot /usr/www/site.ownindex/htdocs
>     AddHandler cgi-script cgi
>     Options ExecCGI indexes

>     <Directory /usr/www/site.ownindex/htdocs/d1>
>     DirectoryIndex hullo.cgi index.html goodbye
>     </Directory>

>     <Directory /usr/www/site.ownindex/htdocs/d2>
>     DirectoryIndex index.html goodbye
>     </Directory>

>     <Directory /usr/www/site.ownindex/htdocs/d3>
>     DirectoryIndex goodbye
>     </Directory>

In ... /htdocs we have five subdirectories, each containing what you would expect to find in ... /htdocs itself, plus the following files:

- hullo.cgi

- index.html

- goodbye

The CGI script hullo.cgi is:

>     #!/bin/sh
>     echo "Content-type: text/html"
>     echo
>     env
>     echo Hi there

The HTML script index.html is:

>     <html>
>     <body>
>     <h1>Index to Butterthlies Catalogs</h1>
>     <ul>
>     <li><A href="catalog_summer.html">Summer catalog </A>
>     <li><A href="catalog_autumn.html">Autumn catalog </A>
>     </ul>
>     <hr>
>     <br>
>     Butterthlies Inc, Hopeful City, Nevada 99999
>     </body>
>     </html>

The text file goodbye is:

>     Sorry, we can't help you. Have a nice day!

The Config file sets up different `DirectoryIndex` options for each subdirectory with a decreasing list of `DirectoryIndex` (es). If hullo.cgi fails for any reason, then index.html is run, and if that fails, we have a polite message in goodbye.

In real life, hullo.cgi might be a very energetic script that really got to work on the clients -- registering their account numbers, encouraging the free spenders, chiding the close-fisted, and generally promoting healthy commerce. Actually, we won't go to all that trouble just now. We will just copy the file /usr/www/mycgi to ... /htdocs/d*/hullo.cgi. If it isn't executable, we have to remember to make it executable in its new home with:

>     chmod +x hullo.cgi

Start Apache with `./go` and access www.butterthlies.com. You see the following:

>     Index of /

>     . Parent Directory
>     . d1
>     . d2
>     . d3
>     . d4
>     . d5

If we select d1, we get:

>     GATEWAY_INTERFACE=CGI/1.1
>     REMOTE_HOST=192.168.123.1
>     REMOTE_ADDR=192.168.123.1
>     QUERY_STRING=
>     DOCUMENT_ROOT=/usr/www/site.ownindex/htdocs
>     HTTP_USER_AGENT=Mozilla/3.0b7 (Win95; I)
>     HTTP_ACCEPT=image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
>     SCRIPT_FILENAME=/usr/www/site.ownindex/htdocs/d1/hullo.cgi
>     HTTP_HOST=www.butterthlies.com
>     SERVER_SOFTWARE=Apache/1.1.1
>     HTTP_CONNECTION=Keep-Alive
>     HTTP_COOKIE=Apache=192287840536604921
>     REDIRECT_URL=/d1/
>     PATH=/sbin:/usr/sbin:/bin:/usr/bin:/usr/local/bin
>     HTTP_REFERER=http://192.168.123.2/
>     SERVER_PROTOCOL=HTTP/1.0
>     REDIRECT_STATUS=200
>     REQUEST_METHOD=GET
>     SERVER_ADMIN=[no address given]
>     SERVER_PORT=80
>     SCRIPT_NAME=/d1/hullo.cgi
>     SERVER_NAME=www.butterthlies.com
>     have a nice day

If we select d2 (or disable ... /d1/hullo.cgi somehow), we should see the output of ... /htdocs/d1/index.html:

>     D2: Index to Butterthlies Catalogs

>     * catalog_summer.html
>     * catalog_autumn.html

>     Butterthlies Inc, Hopeful City, Nevada 99999

If we select d3, we get:

>     Sorry, we can't help you. Have a nice day!

If we select d4, we get:

>     Index of /d4
>     . Parent Directory
>     . bath.jpg
>     . bench.jpg
>     . catalog_autumn.html
>     . catalog_summer.html
>     . hen.jpg
>     . tree.jpg

In directory d5, we have the contents of d1, plus a .htaccess file that contains:

>     DirectoryIndex hullo.cgi index.html.ok goodbye

This gives us the same three possibilities as before. It may be worth remembering that using entries in .htaccess is much slower than using entries in the Config file, because the directives in the ... /conf files are loaded when Apache starts, whereas .htaccess is consulted each time a client accesses the site.

Generally, the `DirectoryIndex` method leaves the ball in your court. You have to write the index.html scripts to do whatever needs to be done, but of course, you have the opportunity to produce something amazing.

Copyright © 2001 O'Reilly & Associates. All rights reserved.